Skip to main content

Get Receiving Events

Method: GET
/events/receiving

As a Customer of iFoodDS, you can use the Get Receiving Event API to query receiving event data from the iFoodDS Trace Exchange platform.

info

This endpoint is being refined and thus subject to change. These docs will update when changes are made.

Request​

Type: application/json

Retrieving receiving events via the API is done through paging. The request requires a series of query parameters which define the page that must be returned. These parameters must be supplied in the url when the get is executed in order to return the result set for the page being queried.

Query Parameters​

Optional​

  • page (number): The page index of the events to return. The first page is index 0.
  • size (number): The number of results to return per page. Default value is 20.
  • submitStartDateTime (datetime): Filters results to include only events submitted after the specified date and time.
  • submitEndDateTime (datetime): Filters results to include only events submitted before the specified date and time.
  • eventStartDateTime (datetime): Filters results to include only events with an event date and time after the specified date and time.
  • eventEndDateTime (datetime): Filters results to include only events with an event date and time before the specified date and time.
  • purchaseOrderNumber: Filters results to include only events exactly matching the specified purchase order number.
  • asnNumber: Filters results to include only events exactly matching the specified ASN (advanced shipping notice) number.
  • shipFromLocationCode: The exact ship from vendor location code on the event.
  • shipToLocationCode: The exact ship to location code on the event.

Data Constraints​

Please note the following data constraints:

  • strings allow a maximum of 100 characters
  • datetimes must use the format: yyyy-MM-ddTHH:mm:ss

Response​

Return result for the receiving event data queried.

{
    "content": [
        {
            "id": "<event id>",
            "eventDateTime": "<event date>",
            "purchaseOrderDate": "<purchase order date>",
            "purchaseOrderNumber": "<purchase order number>",
            "billOfLadingNumber": "<bol number>",
            "asnNumber": "<ASN (advanced shipping notice) number>",
            "expectedDeliveryDate": "<expected delivery date>",
            "shipFromLocationCode": "<ship from vendor location code>",
            "shipToLocationCode": "<ship to location code>",
            "productList": [
                {
                    "palletId": "<pallet id>",
                    "palletLayers": "<pallet layers>",
                    "cartonsPerLayer": "<cartons per layer>",
                    "poLineNumber": "<purchase order line number>",
                    "vendorItemCode": "<vendor item code>",
                    "purchaserItemCode": "<purchaser item code>",
                    "caseGtin": "<case GTIN (Global Trade Identification Number)",
                    "caseLotNumber": "<case lot number>",
                    "shipQuantity": "<pallet quantity>",
                    "shipQuantityUom": "<ship quantity uom> (Units of Measure)",
                    "expirationDate": "<expiration date>",
                    "productionDate": "<production date>",
                    "packagingDate": "<packaging date>",
                    "bestBeforeDate": "<best before date>",
                    "harvestDate": "<harvest date>",
                    "countryOfOrigin": "<country of origin>",
                    "tlcSourceReferenceDuns": "<TLC source reference duns>",
                    "tlcSourceReferenceGln": "<TLC source reference gln>",
                    "tlcSourceReferenceFfrn": "<TLC source reference ffrn>"
                    "tlcSourceReferenceFei": "<TLC source reference fei>"
                    "tlcSourceReferenceUrl": "<TLC source reference url>",
                    "tlcSourceReferenceOther": "<TLC source reference other>",
                    "tlcSourceName": "<TLC source name>",
                    "tlcSourceAddress1": "<TLC source address 1>",
                    "tlcSourceAddress2": "<TLC source address 2>",
                    "tlcSourceCity": "<TLC source city>",
                    "tlcSourceState": "<TLC source state>",
                    "tlcSourcePostalCode": "<TLC source postal code>",
                    "tlcSourcePhoneNumber": "<TLC source phone number>",
                    "itemUpc": "<product UPC (Universal Product Code)>",
                    "itemPlu": "<product PLU>",
                    "itemDateCode": "<product date code>",
                    "itemDateCodeType": "<product date code type>"
                }
            ]
        }
    ],
    "pageable": {
        "pageNumber": <page number>,
        "pageSize": <page size>,
        "sort": {
            "unsorted": <is unsorted>,
            "sorted": <is sorted>,
            "empty": <is page empty>
        },
        "offset": <offset size>,
        "unpaged": <is unpaged>,
        "paged": <is paged>
    },
    "totalPages": <total pages>,
    "totalElements": <total elements>,
    "last": <is last page>,
    "numberOfElements": <number of elements>,
    "size": <page size>,
    "number": <page number>,
    "sort": {
        "unsorted": <is unsorted>,
        "sorted": <is sorted>,
        "empty": <is empty>
    },
    "first": <is first page>,
    "empty": <is page empty>
}

Content​

  • id (uuid): The unique id of the event
  • eventDateTime (datetime): Date and time the order was actually received
  • purchaseOrderDate (date): Purchase order date
  • purchaseOrderNumber (string): The purchase order number you received from your customer
  • billOfLadingNumber (string): The Bill of Lading provided by you to your customer
  • asnNumber (string): This is the unique identifier for the ASN you provide to your customer (if you provide one)
  • expectedDeliveryDate (date): Date when shipper expects to deliver goods to recipient
  • shipFromLocationCode (string): The vendor’s location code for ship from location
  • shipToLocationCode (string): The buyer’s location code for ship to location. This should be provided as part of the Purchase Order
  • productList (object[])
    • palletId (string): GS1 Serial Shipping Container Code, SSCC-18 (if provided) 
    • palletLayers (number): Number of layers per pallet
    • cartonsPerLayer (number): Number of cartons per layer
    • poLineNumber (string): Line number in the purchase order for this item; this links the Traceability Lot Code to the line item on the PO
    • vendorItemCode (string): This is the vendor's (or your) internal product id or item code stored in their master data. If the cases shipped are labeled with a case GTIN-14, this information should be stored in the product master data record for the item code / product id referenced
    • purchaserItemCode (string): This is the purchaser's product item code provided via their PO or other form of data sharing. This information is stored in your master data. If the customer has shared a GTIN, it should be stored in the master data record. The purchaser's item code may also be the purchaser’s GTIN, but not necessarily-–it could be a SKU or another type of ID. This may point to the receiver’s master product data record
    • caseGtin (string): GTIN-14 of cases on pallet
    • caseLotNumber (string): This is the Lot Number displayed on the case label you are providing to the customer. This will be required starting in January 2026
    • shipQuantity (number): The number of units of this Traceability Lot Code on the pallet
    • shipQuantityUom (string): Unit of measure (e.g., Case)
    • expirationDate (date): The expiration date
    • productionDate (date): The production date
    • packagingDate (date): The packaging date
    • bestBeforeDate (date): The best before date
    • harvestDate (date): The harvesting date
    • countryOfOrigin (string): The three letter country code of origin
    • tlcSourceReferenceDuns (string): 9 Digit Dun & Bradstreet Number, must be registered in DUNS and available to FDA. The TLC Source reference DUNS + 4
    • tlcSourceReferenceGln (string): 13 Digit GS1 Global Location Number. Must be registered in GS1 US Data Hub | Location. The TLC Source reference GLN
    • tlcSourceReferenceFfrn (string): FDA Food Facility Registration Number, must be current in FDA Facility Regisration Database. The TLC Source reference FFRN
    • tlcSourceReferenceFei (string): FDA Establishment Identifier. This number may be requested at no cost from FDA. The TLC Source reference FEI
    • tlcSourceReferenceUrl (string): A web link point to a site where FDA may access the TLC Source Reference. The TLC Source reference URL
    • tlcSourceReferenceOther (string): This could be another identifier. One can prefix the ID with a type to make it easier to lookup. For example: 'USDAEgg: Plant 42"
    • tlcSourceName (string): The TLC source name
    • tlcSourceAddress1 (string): The TLC Source physical street address line 1 information
    • tlcSourceAddress2 (string): The TLC Source physical street address line 2 information, if applicable
    • tlcSourceCity (string): The TLC Source city location
    • tlcSourceState (string): The TLC Source state or region location
    • tlcSourcePostalCode (string): The TLC Source ZIP or postal code
    • tlcSourceCountry (string): The TLC Source country
    • tlcSourcePhoneNumber (string): The TLC Source phone number
    • itemUpc (string): Item-level Universal Product Code, may be GTIN-8, GTIN-12, or GTIN-13. GS1 GTIN Executive Summary
    • itemPlu (string): Include if items in the case are marked with PLU numbers; this may be used instead of UPC
    • itemDateCode (date): Often items are marked with a date code; if so, this field can be used to capture it
    • itemDateCodeType (string): Indicate the type of date code if provided

Pageable​

  • pageable (object)
    • pageNumber (number): The current page number in the page series. Index 0 is first page
    • pageSize (number): The number of events contained in the page
    • offset (number): If there is an offset specified on there return results this will be populates. Default is 0
    • unpaged (boolean): If the record set is unpaged then true else false
    • paged (boolean): If the record set is paged then true else false
    • sort (object)
      • unsorted (boolean): If the record set is unsorted then true else false
      • sorted (boolean): If the record set is sorted then true else false
      • empty (boolean): If the record set is empty then true else false
  • totalPages (number): The total amount of pages that contain all events in the query
  • totalElements (number): The total amount of events in the query
  • last (boolean): If the page is the last in the series then true else false
  • numberOfElements (number): The total amount of events in the table
  • size (number): The number of events contained in the page
  • number (number): The current page number in the page series
  • sort (object)
    • unsorted (boolean): If the record set is unsorted then true else false
    • sorted (boolean): If the record set is sorted then true else false
    • empty (boolean): If the record set is empty then true else false
  • first (boolean): If the page is the first in the series then true else false
  • empty (boolean): If the page is empty then true else false